<html>
<head>
<title>PDS4 -- NASA Planetary Data System (Version 4)</title>
</head>

<body bgcolor="#ffffff">

<h1>PDS4 -- NASA Planetary Data System (Version 4)</h1>

PDS4 is a format used primarily by NASA to store and distribute
solar, lunar and planetary imagery data.  GDAL provides read-write
access to PDS4 formatted imagery data.<p>

PDS4 files are compose of a .xml (label) file which references a raw imagery
file. The driver also supports imagery stored in a separate uncompressed
GeoTIFF file with a strip organization compatible of a raw imagery file.<p>

The driver also reads and write georeferencing and coordinate system information
as well as selected other header metadata.<p>

If several Array objects are present in the label, they will be reported as
separate subdatasets (typically the main subdataset is an Array3D, and
backplanes are represented as Array2D). Creation of new datasets with
subdatasets is not supported: only a single Array3D with possibly multiple bands
is supported.<p>

A mask band is attached to each source band. The
value of this mask band is 0 when the pixel value is one of the missing constants.<p>

Implementation of this driver was supported by the United States
Geological Survey.<p>

PDS4 is part of a family of related formats including PDS and ISIS3.<p>

<h2>Metadata</h2>

<p>The PDS4 label can be retrieved as XML-serialized
content in the xml:PDS4 metadata domain.</p>

<p>On creation, a source template label can be passed to the SetMetadata()
interface in the "xml:PDS4" metadata domain.</p>

<h2>Creation support</h2>

<p>The PDS4 driver supports updating imagery of
existing datasets, creating new datasets through the CreateCopy() and Create()
interfaces.</p>

<p>When using CreateCopy(), gdal_translate or gdalwarp, an effort is made to
preserve as much as possible of the original label when doing PDS4 to PDS4
conversions. This can be disabled with the USE_SRC_LABEL=NO creation option.
</p>

<p>The available creation options are:</p>
<ul>
<li> <b>IMAGE_FILENAME</b>=filename. Override default external image filename.</li>
<li> <b>IMAGE_EXTENSION</b>=ext. Override default extension of the external
image filename. The default is 'img' for IMAGE_FORMAT=RAW or 'tif' for
IMAGE_FORMAT=GEOTIFF</li>
<li> <b>IMAGE_FORMAT</b>=RAW/GEOTIFF. Format of the image file.
If using RAW, the imagery is put in a raw file whose filename is the main
filename with a .img extension. If using GEOTIFF, the imagery is put in a
separate GeoTIFF file, whose filename is the main filename with a .tif
extension. Defaults to RAW</li>
<li> <b>INTERLEAVE</b>=BSQ/BIP/BIL. Pixel organization in the image file.
BSQ is Band SeQuential, BIP is Band Interleaved per Pixel and BIL is Band
Interleave Per Line. The default is BSQ. BIL is not valid for
IMAGE_FORMAT=GEOTIFF</li>
<li> <b>VAR_*</b>=string. If options like VAR_XXXX=yyyy are specified, any
{XXXX} string in the template label will be replaced by the yyyy value.</li>
<li> <b>TEMPLATE</b>=filename. Template label to use. If not specified and
not creating from an existing PDS4 file, the data/pds4_template.xml file will
be used. For GDAL utilities to find this default PDS4 template, GDAL's data
directory should be defined in your environment (typically on Windows builds).
Consult the <a href="https://trac.osgeo.org/gdal/wiki/FAQInstallationAndBuilding#HowtosetGDAL_DATAvariable">wiki
</a> for more information.</li>
<li> <b>USE_SRC_LABEL</b>=YES/NO. Whether to use the source label in PDS4 to
PDS4 conversions. Defaults to YES.</li>
<li> <b>LATITUDE_TYPE</b>=planetocentric/planetographic. Value of latitude_type.
Defaults to planetocentric.</li>
<li> <b>LONGITUDE_DIRECTION</b>=Positive East/Positive West.
Value of longitude_direction. Defaults to Positive East.</li>
<li> <b>RADII</b>=semi_major_radius,semi_minor_radius.
To override the ones of the SRS. Note that the first value (semi_major_radius)
will be used to set the &lt;pds:semi_major_radius&gt; and
&lt;pds:semi_minor_radius&gt; XML elements, and that second value
(semi_minor_radius) will be used to set the &lt;pds:polar_radius&gt; XML element.</li>
<li> <b>ARRAY_TYPE</b>=Array/Array_2D/Array_2D_Image/Array_2D_Map/
Array_2D_Spectrum/Array_3D/Array_3D_Image/Array_3D_Movie/Array_3D_Spectrum.
To set the XML element that defines the type of array. Defaults to Array_3D_Image.
Using a Array_2D* for a multiband image is not supported. When using a
Array_2D* value, INTERLEAVE will be ignored.</li>
<li> <b>BOUNDING_DEGREES</b>=west_lon,south_lat,east_lon,north_lat. Manually set
bounding box</li>
</ul>

<h2>Examples:</h2>

<li>Listing bands and subdatasets:</li>

<pre>$ gdalinfo b0011_p237201_01_01v02.xml

Driver: PDS4/NASA Planetary Data System 4
Files: b0011_p237201_01_01v02.xml
       b0011_p237201_01_01v02.qub
Size is 512, 512
Coordinate System is `'
Image Structure Metadata:
  INTERLEAVE=BAND
Subdatasets:
  SUBDATASET_1_NAME=PDS4:b0011_p237201_01_01v02.xml:1:1
  SUBDATASET_1_DESC=Image file b0011_p237201_01_01v02.qub, array Spectral_Qube_Object
  SUBDATASET_2_NAME=PDS4:b0011_p237201_01_01v02.xml:1:2
  SUBDATASET_2_DESC=Image file b0011_p237201_01_01v02.qub, array iof_r2
  SUBDATASET_3_NAME=PDS4:b0011_p237201_01_01v02.xml:1:3
  SUBDATASET_3_DESC=Image file b0011_p237201_01_01v02.qub, array iof_r7
  SUBDATASET_4_NAME=PDS4:b0011_p237201_01_01v02.xml:1:4
[...]
  SUBDATASET_16_DESC=Image file b0011_p237201_01_01v02.qub, array emission_angle
  SUBDATASET_17_NAME=PDS4:b0011_p237201_01_01v02.xml:1:17
  SUBDATASET_17_DESC=Image file b0011_p237201_01_01v02.qub, array phase_angle
  SUBDATASET_18_NAME=PDS4:b0011_p237201_01_01v02.xml:1:18
  SUBDATASET_18_DESC=Image file b0011_p237201_01_01v02.qub, array approx_incidence_angle
  SUBDATASET_19_NAME=PDS4:b0011_p237201_01_01v02.xml:1:19
  SUBDATASET_19_DESC=Image file b0011_p237201_01_01v02.qub, array approx_emission_angle
  SUBDATASET_20_NAME=PDS4:b0011_p237201_01_01v02.xml:1:20
  SUBDATASET_20_DESC=Image file b0011_p237201_01_01v02.qub, array approx_phase_angle
Corner Coordinates:
Upper Left  (    0.0,    0.0)
Lower Left  (    0.0,  512.0)
Upper Right (  512.0,    0.0)
Lower Right (  512.0,  512.0)
Center      (  256.0,  256.0)
Band 1 Block=512x1 Type=Int16, ColorInterp=Undefined
  Offset: 0.146998785514825,   Scale:4.48823844390647e-06
Band 2 Block=512x1 Type=Int16, ColorInterp=Undefined
  Offset: 0.146998785514825,   Scale:4.48823844390647e-06
Band 3 Block=512x1 Type=Int16, ColorInterp=Undefined
  Offset: 0.146998785514825,   Scale:4.48823844390647e-06
Band 4 Block=512x1 Type=Int16, ColorInterp=Undefined
  Offset: 0.146998785514825,   Scale:4.48823844390647e-06
Band 5 Block=512x1 Type=Int16, ColorInterp=Undefined
  Offset: 0.146998785514825,   Scale:4.48823844390647e-06
</pre>

<p>
The information displayed by default is the one of the first subdataset
(SUBDATASET_1_NAME)
</p>

<li>Getting information on a subdataset:</li>

<pre>$ gdalinfo PDS4:b0011_p237201_01_01v02.xml:1:2

Driver: PDS4/NASA Planetary Data System 4
Files: b0011_p237201_01_01v02.xml
       b0011_p237201_01_01v02.qub
Size is 512, 512
Coordinate System is `'
Corner Coordinates:
Upper Left  (    0.0,    0.0)
Lower Left  (    0.0,  512.0)
Upper Right (  512.0,    0.0)
Lower Right (  512.0,  512.0)
Center      (  256.0,  256.0)
Band 1 Block=512x1 Type=Int16, ColorInterp=Undefined
  Offset: 0.04984971,   Scale:7.454028e-06
</pre>

<li>Conversion to GeoTIFF of a given subdatasets:</li>

<pre>$ gdal_translate PDS4:b0011_p237201_01_01v02.xml:1:2 iof_r2.tif</pre>

<li>Conversion to GeoTIFF of a all subdatasets:</li>

<pre>$ gdal_translate -sds b0011_p237201_01_01v02.xml b0011_p237201_01_01v02.tif</pre>

<p>This will create b0011_p237201_01_01v02_X.tif files where X=1,....,N</pre>

<li>Creation of a new PDS4 dataset, using the default template and setting
its parameterized variables:</li>

<pre>$ gdal_translate input.tif output.xml -of PDS4 \
            -co VAR_TARGET_TYPE=Satellite \
            -co VAR_Target=Moon \
            -co VAR_OBSERVING_SYSTEM_NAME=LOLA \
            -co VAR_LOGICAL_IDENTIFIER=Lunar_LRO_LOLA_DEM_Global_64ppd.tif \
            -co VAR_TITLE="LRO LOLA Digital Elevation Model (DEM) 64ppd" \
            -co VAR_INVESTIGATION_AREA_NAME="Lunar Reconnaissance Orbiter" \
            -co VAR_INVESTIGATION_AREA_LID_REFERENCE="urn:nasa:pds:context:instrument_host:spacecraft.lro"
</pre>

<li>Creation of the same PDS4 dataset as above, using the default template but
setting its parameterized variables from a text file. Helps with long command
lines:</li>
<p>
Create a text file "myOptions.txt" with the below content</p>
<pre>
#This is a comment
#Conversion parameters for the LRO LOLA dataset
-co VAR_TARGET_TYPE=Satellite 
-co VAR_Target=Moon 
-co VAR_OBSERVING_SYSTEM_NAME=LOLA 
-co VAR_LOGICAL_IDENTIFIER=Lunar_LRO_LOLA_DEM_Global_64ppd.tif
-co VAR_TITLE="LRO LOLA Digital Elevation Model (DEM) 64ppd"
-co VAR_INVESTIGATION_AREA_NAME="Lunar Reconnaissance Orbiter"
-co VAR_INVESTIGATION_AREA_LID_REFERENCE="urn:nasa:pds:context:instrument_host:spacecraft.lro"
#end of file
</pre>

<pre>
gdal_translate input.tif output.xml -of PDS4 --optfile myOptions.txt
</pre>
<p>
For more on --optfile, consult <a href="gdal_utilities.html">the general
documentation on GDAL utilities</a>.</p>


<li>Creation of a PDS4 dataset, using a non default template (here on a
HTTP server, but local filename also possible):</li>

<pre>$ gdal_translate input.tif output.xml -of PDS4 \
            -co TEMPLATE=http://example.com/mytemplate.xml
</pre>

<li>Creation of a PDS4 dataset from a source PDS4 dataset (using the XML file of
this source PDS4 dataset as an implicit template), with subsetting:</li>

<pre>$ gdal_translate input.xml output.xml -of PDS4 -projwin ullx ully lrx lry</pre>

<li>In Python, creation of a PDS4 dataset from a GeoTIFF, using a base template into
which one substitute one element with a new value:</li>

<pre>
from osgeo import gdal
from lxml import etree

# Customization of template
template = open('template.xml','rb').read()
root = etree.XML(template)
ns = '{http://pds.nasa.gov/pds4/pds/v1}'
identifier = root.find(".//{ns}Identification_Area/{ns}logical_identifier".format(ns = ns))
identifier.text = 'new_identifier'

# Serialize the modified template in a in-memory file
in_memory_template = '/vsimem/template.xml'
gdal.FileFromMemBuffer(in_memory_template, etree.tostring(root))

# Create the output dataset
gdal.Translate('out.xml', 'in.tif', format = 'PDS4',
               creationOptions = ['TEMPLATE='+in_memory_template])

# Cleanup
gdal.Unlink(in_memory_template)
</pre>

<h2>Limitations</h2>

<ul>
<li>No support for the creation of subdatasets</li>
<li>No PDS4 table support</li>
</ul>

<p>
As a new driver and new format, please report any issues to the bug tracker,
as explained on the <a href="https://trac.osgeo.org/gdal/wiki">wiki</a>
</p>

<h2>See Also:</h2>

<ul>
<li> Implemented as <tt>gdal/frmts/pds/pds4dataset.cpp</tt>. </li>
<li> <a href="https://pds.nasa.gov/pds4/doc/index.shtml">Official documentation</a> </li>
<li> <a href="https://pds.nasa.gov/pds4/schema/released/">Schemas, including the cartography extension</a> </li>
<li> <a href="frmt_pds.html">GDAL PDS Driver</a> </li>
<li> <a href="frmt_isis3.html">GDAL ISIS3 Driver</a> </li>
</ul>

</body>
</html>
